Converting External Files

ConverTable Units 2.3 introduced the ability to convert values in external files.  This document describes this new feature, and how you can utilize it.  This feature allows you to convert hundreds or even thousands of values with just a few clicks!   As this is a new and evolving feature, if you have suggestions or comments about how this part of ConverTable Units should work, please let us know:

http://www.synergycreations.com/contact.html

The included "Sample External File (m).txt" is an example file containing values in meters.  You should open and examine this file to get an idea of how external files can be structured.

File Types

The file to be converted must be a Macintosh ASCII text file.
In other words, the line endings cannot be Windows or Unix style.
The file's creator must be "TEXT" and/or the file extension can be
.asc, .ascii, .text, or .txt
You can make text files in many programs.  Bare Bones Software, www.barebones.com, makes some excellent Macintosh text editors, including BBEdit and TextWrangler.  They formerly produced a free program, BBEdit Lite, which is also excellent, and may still be found on some internet software archive sites.  Some word processing programs can produce text files, but you must specifically tell them to save the file as a text file, and not the word processor's native file, which generally includes many formatting codes.

File Contents

The file should be a list of values to be converted, one value per line.
Example:

43.1
45.3
25.63
64.4
75.3

If the values use scientific notation, it should be written using the "E" format.  For example:

4.4E10
5.32E-12

The conversion process has been tested with input files up to ~1.0 MB and ~300,000 lines long.  It should work with larger files, although it may be quite slow, depending on your processor speed and size of the file being converted.  Also, if you are not using Mac OS X, you may need to increase the memory allocation for ConverTable Units.  (File>Get Info in the Finder.)

Output File Formatting

The format of the output file will match the format settings in ConverTable Units' "Result" menu.  Set these up before you make the file conversion.

File Headers

Optionally, header lines can be included before the value lines.  If header lines are included, the first line must be

startline=N

where N-1 is the total number of header lines, and N is the line where ConverTable Units should begin looking for values.  So if the first line is "startline=25", 24 header lines will be skipped and ConverTable Units will attempt to convert values on all lines from 25 until the end of the file.

If you choose to include header lines, you can include as the second line in the file a "unit=" line.

unit=STRING

where STRING is a unit name, as it appears in a ConverTable Units pop-up menu.  For example,

unit=meter
unit=cubic decimeter
unit=weber/square meter

The unit=STRING line is designed to help avoid conversion mistakes.  It is not required (in fact, no header lines are required).  If it is present, however, ConverTable Units will require that you are converting from the baseunit.

Making the Conversion

First, set up the conversion you want to make in ConverTable Units, as if you were converting single values in the program normally.  Choose your category from the "Convert" menu, then the input and output units from the unit popup menus.  You can use any built-in or plug-in unit category.

Once you have your conversion designed, press COMMAND-O (or select "Open And Convert External File…" from the "File" menu).

ConverTable Units will open a dialog describing the conversion what you are about to do.  The conversion factor is calculated at that moment**.

Click "Continue" to dismiss the dialog.

Now you can select a text file containing the list of values you want to convert.  Find the original file you want to convert and click "Select".  A sample file containing values in meters is provided with ConverTable Units: "Sample External File (m).txt"

ConverTable Units will examine the file you've selected.  If the file has header lines or defined units, this information is displayed as well.  If the file's defined unit does not match your starting unit for the conversion, a message will explain this.  In this case, you need to either cancel the conversion, or use the "Reselect" button to choose a different file.  If everything checks out, click "Continue".

Now you can type a name for the converted file, and indicate where you want it to be saved.  When you've named the converted file and found where you want to save it, click "Save".

The conversion now happens.  This may take some time for large files, but is generally fairly fast.

That's it!  You can now open your converted file in a text editor (or whatever program you use) to see the converted values.  Any header lines in the original file are copied into the converted file, except the "unit=" line.  If it exists in the original file, the "unit=" line is updated to reflect the new unit in the converted file. 

If your converted file contains zeros, check to make sure your formatting settings in the "Result" menu of ConverTable Units will produce visible, non-zero results with sample data.  (This often happens if you specifiy no scientific notation and a small number of decimal places.  There is no way to display a number like 1e-30 if you've set the result formatting to no scientific notation and 1 decimal place!)

**If the conversion factor displayed isn't what you want or expect, this may be due to the autoformatting getting confused.  Often, the actual conversion factor being used is more accurate than what ConverTable Units displays at this point. If the conversion works in the "normal" one-value-at-a-time way of using ConverTable Units, it should work when you convert values in external files, provided your output formatting ("Result" menu) is appropriate for the values you've entered.  If you encounter problems here, please email problems@synergycreations.com , preferably with examples where ConverTable Units fails.

©2003 Synergy Creations™  All Rights Reserved.